

    \filetitle{simulate}{Simulate model}{model/simulate}

	\paragraph{Syntax}

\begin{verbatim}
S = simulate(M,D,Range,...)
[S,Flag,AddF,Delta] = simulate(M,D,Range,...)
\end{verbatim}

\paragraph{Input arguments}

\begin{itemize}
\item
  \texttt{M} {[} model {]} - Solved model object.
\item
  \texttt{D} {[} struct \textbar{} cell {]} - Input database or datapack
  from which the initial conditions and shocks from within the
  simulation range will be read.
\item
  \texttt{Range} {[} numeric \textbar{} char {]} - Simulation range.
\end{itemize}

\paragraph{Output arguments}

\begin{itemize}
\tightlist
\item
  \texttt{S} {[} struct \textbar{} cell {]} - Database with simulation
  results.
\end{itemize}

\paragraph{Output arguments in nonlinear
simulations}

\begin{itemize}
\item
  \texttt{ExitFlag} {[} cell \textbar{} empty {]} - Cell array with exit
  flags for nonlinearised simulations.
\item
  \texttt{AddF} {[} cell \textbar{} empty {]} - Cell array of tseries
  with final add-factors added to first-order approximate equations to
  make nonlinear equations hold.
\item
  \texttt{Delta} {[} cell \textbar{} empty {]} - Cell array of tseries
  with final discrepancies between LHS and RHS in equations marked for
  nonlinear simulations by a double-equal sign.
\end{itemize}

\paragraph{Options}

\begin{itemize}
\item
  \texttt{\textquotesingle{}anticipate=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - If \texttt{true},
  real future shocks are anticipated, imaginary are unanticipated; vice
  versa if \texttt{false}.
\item
  \texttt{\textquotesingle{}contributions=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Decompose the
  simulated paths into contributions of individual shocks.
\item
  \texttt{\textquotesingle{}dbOverlay=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} \textbar{} struct {]} -
  Use the function \texttt{dboverlay} to combine the simulated output
  data with the input database, (or a user-supplied database); both the
  data preceeding the simulation range and after the simulation range
  are appended.
\item
  \texttt{\textquotesingle{}deviation=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Treat input and
  output data as deviations from balanced-growth path.
\item
  \texttt{\textquotesingle{}dTrends=\textquotesingle{}} {[}
  \emph{\texttt{@auto}} \textbar{} \texttt{true} \textbar{}
  \texttt{false} {]} - Add deterministic trends to measurement
  variables.
\item
  \texttt{\textquotesingle{}ignoreShocks=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Read only initial
  conditions from input data, and ignore any shocks within the
  simulation range.
\item
  \texttt{\textquotesingle{}method=\textquotesingle{}} {[}
  \emph{\texttt{\textquotesingle{}firstorder\textquotesingle{}}}
  \textbar{} \texttt{\textquotesingle{}selective\textquotesingle{}}
  \textbar{} \texttt{\textquotesingle{}global\textquotesingle{}} {]} -
  Method of running simulations;
  \texttt{\textquotesingle{}firstorder\textquotesingle{}} means
  first-order approximate solution (calculated around steady state);
  \texttt{\textquotesingle{}selective\textquotesingle{}} means
  equation-selective nonlinear method;
  \texttt{\textquotesingle{}global\textquotesingle{}} means global
  nonlinear method (available only in models with no leads).
\item
  \texttt{\textquotesingle{}plan=\textquotesingle{}} {[} plan {]} -
  Specify a simulation plan to swap endogeneity and exogeneity of some
  variables and shocks temporarily, and/or to simulate some nonlinear
  equations.
\item
  \texttt{\textquotesingle{}progress=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Display progress
  bar in the command window.
\item
  \texttt{\textquotesingle{}sparseShocks=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Store anticipated
  shocks (including endogenized anticipated shocks) in sparse array.
\end{itemize}

\paragraph{Options for equation-selective nonlinear
simulations}

\begin{itemize}
\item
  \texttt{\textquotesingle{}solver=\textquotesingle{}} {[}
  \emph{\texttt{@qad}} \textbar{} \texttt{@fsolve} \textbar{}
  \texttt{@lsqnonlin} {]} - Solution algorithm; see Description.
\item
  \texttt{\textquotesingle{}maxNumelJv=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{1e6}} {]} - Maximum number of data points
  (nonlinear plus exogenized) allowed for a nonrecursive algorithm in
  the nonlinear equation updating step; if exceeded, a recursive
  (period-by-period) simulation is used to update nonlinear equations
  instead.
\item
  \texttt{\textquotesingle{}nonlinPer=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{@all}} {]} - Horizon (number of periods from
  the beginning of the simulation, and from the beginning of each
  simulation segment) over which nonlinearities will be preserved; the
  remaining periods will be simulated using first-order approximate
  solution.
\end{itemize}

\paragraph{Options for equation-selective nonlinear simulations with
@qad
solver}

\begin{itemize}
\item
  \texttt{\textquotesingle{}addSstate=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - Add steady state
  levels to simulated paths before evaluating nonlinear equations; this
  option is used only if
  \texttt{\textquotesingle{}deviation=\textquotesingle{}\ true}.
\item
  \texttt{\textquotesingle{}display=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} \textbar{} numeric
  \textbar{} Inf {]} - Report iterations on the screen; if
  \texttt{\textquotesingle{}display=\textquotesingle{}\ N}, report every
  \texttt{N} iterations; if
  \texttt{\textquotesingle{}display=\textquotesingle{}\ Inf}, report
  only final iteration.
\item
  \texttt{\textquotesingle{}error=\textquotesingle{}} {[} \texttt{true}
  \textbar{} \emph{\texttt{false}} {]} - Throw an error whenever a
  nonlinear simulation fails converge; if \texttt{false}, only an
  warning will display.
\item
  \texttt{\textquotesingle{}lambda=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{1}} {]} - Initial step size (between
  \texttt{0} and \texttt{1}) for add factors added to nonlinearised
  equations in every iteration; see also
  \texttt{\textquotesingle{}nOptimLambda=\textquotesingle{}}.
\item
  \texttt{\textquotesingle{}nOptimLambda=\textquotesingle{}} {[} numeric
  \textbar{} \texttt{false} \textbar{} \emph{\texttt{1}} {]} - Find the
  optimal step size on a grid of 10 points between 0 and
  \texttt{\textquotesingle{}lambda=\textquotesingle{}} before each of
  the first \texttt{\textquotesingle{}nOptimLambda=\textquotesingle{}}
  iterations; if \texttt{false}, the value assigned to \texttt{Lambda}
  is used and no grid search is performed.
\item
  \texttt{\textquotesingle{}reduceLambda=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{0.5}} {]} - Reduction factor (between
  \texttt{0} and \texttt{1}) by which \texttt{lambda} will be multiplied
  if the nonlinear simulation gets on an divergence path.
\item
  \texttt{\textquotesingle{}upperBound=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{1.5}} {]} - Multiple of all-iteration minimum
  achieved that triggers a reversion to that iteration and a reduciton
  in \texttt{lambda}.
\item
  \texttt{\textquotesingle{}maxIter=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{100}} {]} - Maximum number of iterations.
\item
  \texttt{\textquotesingle{}tolerance=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{1e-5}} {]} - Convergence tolerance.
\end{itemize}

\paragraph{Options for nonlinear simulations with Optim Tbx
solver}

\begin{itemize}
\tightlist
\item
  \texttt{\textquotesingle{}optimSet=\textquotesingle{}} {[} cell
  \textbar{} struct {]} - Optimization Tbx options.
\end{itemize}

\paragraph{Options for global nonlinear
simulations}

\begin{itemize}
\item
  \texttt{\textquotesingle{}optimSet=\textquotesingle{}} {[} cell
  \textbar{} struct {]} - Optimization Tbx options.
\item
  \texttt{\textquotesingle{}solver=\textquotesingle{}} {[}
  \texttt{@fsolve} \textbar{} \emph{\texttt{@lsqnonlin}} {]} - Solution
  algorithm; see Description.
\end{itemize}

\paragraph{Description}

The function \texttt{simulate(...)} simulates a model on the specified
simulation range. By default, the simulation is based on a first-order
approximate solution (calculated around steady state). To run nonlinear
simulations, use the option
\texttt{\textquotesingle{}nonlinear=\textquotesingle{}} (to set the
number of periods

\subparagraph{Output range}

Time series in the output database, \texttt{S}, are are defined on the
simulation range, \texttt{Range}, plus include all necessary initial
conditions, ie. lags of variables that occur in the model code. You can
use the option \texttt{\textquotesingle{}dboverlay=\textquotesingle{}}
to combine the output database with the input database (ie. to include a
longer history of data in the simulated series).

\subparagraph{Deviations from steady-state and deterministic
trends}

By default, both the input database, \texttt{D}, and the output
database, \texttt{S}, are in full levels and the simulated paths for
measurement variables include the effect of deterministic trends,
including possibly exogenous variables. The default behavior can be
changed by changing the options
\texttt{\textquotesingle{}deviation=\textquotesingle{}} and
\texttt{\textquotesingle{}dTrends=\textquotesingle{}}.

The default value for
\texttt{\textquotesingle{}deviation=\textquotesingle{}} is false. If set
to \texttt{true}, then the input database is expected to contain data in
the form of deviations from their steady state levels or paths. For
ordinary variables (ie. variables whose log status is \texttt{false}),
it is \(x_t-\Bar x_t\), meaning that a 0 indicates that the variable is
at its steady state and e.g.~2 indicates the variables exceeds its
steady state by 2. For log variables (ie. variables whose log status is
\texttt{true}), it is \(x_t/\Bar x_t\), meaning that a 1 indicates that
the variable is at its steady state and e.g.~1.05 indicates that the
variable is 5 per cent above its steady state.

The default value for
\texttt{\textquotesingle{}dTrends=\textquotesingle{}} is \texttt{@auto}.
This means that its behavior depends on the option
\texttt{\textquotesingle{}deviation=\textquotesingle{}}. If
\texttt{\textquotesingle{}deviation=\textquotesingle{}\ false} then
deterministic trends are added to measurement variables, unless you
manually override this behavior by setting
\texttt{\textquotesingle{}dTrends=\textquotesingle{}\ false}. On the
other hand, if
\texttt{\textquotesingle{}deviation=\textquotesingle{}\ true} then
deterministic trends are not added to measurement variables, unless you
manually override this behavior by setting
\texttt{\textquotesingle{}dTrends=\textquotesingle{}\ true}.

\subparagraph{Simulating contributions of
shocks}

Use the option
\texttt{\textquotesingle{}contributions=\textquotesingle{}\ true} to
request the contributions of shocks to the simulated path for each
variable; this option cannot be used in models with multiple alternative
parameterizations or with multiple input data sets.

The output database, \texttt{S}, contains Ne+2 columns for each
variable, where Ne is the number of shocks in the model:

\begin{itemize}
\item
  the first columns 1\ldots{}Ne are the contributions of the Ne
  individual shocks to the respective variable;
\item
  column Ne+1 is the contribution of initial condition, th econstant,
  and deterministic trends, including possibly exogenous variables;
\item
  column Ne+2 is the contribution of nonlinearities in nonlinear
  simulations (it is always zero otherwise).
\end{itemize}

The contributions are additive for ordinary variables (ie. variables
whose log status is \texttt{false}), and multplicative for log variables
(ie. variables whose log status is \texttt{true}). In other words, if
\texttt{S} is the output database from a simulation with
\texttt{\textquotesingle{}contributions=\textquotesingle{}\ true},
\texttt{X} is an ordinary variable, and \texttt{Z} is a log variable,
then

\begin{verbatim}
sum(S.X,2)
\end{verbatim}

(ie. the sum of all Ne+2 contributions in each period, ie. summation
goes across 2nd dimension) reproduces the final simulated path for the
variable \texttt{X}, whereas

\begin{verbatim}
prod(S.Z,2)
\end{verbatim}

(ie. the product of all Ne+2 contributions) reproduces the final
simulated path for the variable \texttt{Z}.

\subparagraph{Simulations with multiple parameterisations and/or
multiple data
sets}

If you simulate a model with \texttt{N} parameterisations and the input
database contains \texttt{K} data sets (ie. each variable is a time
series with \texttt{K} columns), then the following happens:

\begin{itemize}
\item
  The model will be simulated a total of \texttt{P\ =\ max(N,K)} number
  of times. This means that each variables in the output database will
  have \texttt{P} columns.
\item
  The 1st parameterisation will be simulated using the 1st data set, the
  2nd parameterisation will be simulated using the 2nd data set, etc.
  until you reach either the last parameterisation or the last data set,
  ie. \texttt{min(N,K)}. From that point on, the last parameterisation
  or the last data set will be simply repeated (re-used) in the
  remaining simulations.
\item
  Formally, the \texttt{I}-th column in the output database, where
  \texttt{I\ =\ 1,\ ...,\ P}, is a simulation of the
  \texttt{min(I,N)}-th model parameterisation using the
  \texttt{min(I,K)}-th input data set number.
\end{itemize}

\subparagraph{Equation-selective nonlinear
simulations}

The equation-selective nonlinear simulation approach is invoked by
setting
\texttt{\textquotesingle{}method=\textquotesingle{}\ \textquotesingle{}selective\textquotesingle{}}.
In equation-selective nonlinear simulations, the solver tries to find
add-factors to user-selected nonlinear equations (ie. equations with
\texttt{=\#} instead of the equal sign in the model file) in the
first-order solution such that the original nonlinear equations hold for
simulated trajectories (with expectations replaced with actual leads).

Two numerical approaches are available, controlled by the option
\texttt{\textquotesingle{}solver=\textquotesingle{}}:

\begin{itemize}
\item
  `\texttt{QaD}' - a quick-and-dirty, but less robust method (default);
\item
  \texttt{@fsolve}, \texttt{@lsqnonlin} - which are standard
  Optimization Tbx routines, slower but likely to converge for a wider
  variety of simulations.
\end{itemize}

\subparagraph{Global nonlinear
simulations}

The global nonlinear simulation approach is invoked by setting
\texttt{\textquotesingle{}method=\textquotesingle{}\ \textquotesingle{}global\textquotesingle{}}
and is available only in models with no leads (expectations). In global
nonlinear simulations, the entire model is solved as a system of
nonlinear equations, period by period, using one of the following two
Optimization Tbx routines: \texttt{@fsolve} or \texttt{@lsqnonlin}
(default).

\paragraph{Example}


